…times

Addresses Codex review point #4 on #9210: getThreadLocalMetadata would
happily return a payload on macOS/Windows or on Node without an active
AsyncContextFrame, which would cause libdatadog to advertise a
threadlocal block that no writer is actually producing. Gate the
function on the same platform + ACF conditions start() already checks,
so callers see 'no threadlocal block'.

Addresses Codex review point #2 on #9210: an OTEP-4947 record can only
carry the first-written value for each attribute key, and HTTP plugins
routinely set 'http.method' up front and add 'http.route' (plus
'resource.name') later once routing has resolved. The writer previously
committed the endpoint on first activation, so a request to '/users/:id'
was recorded as 'GET' forever.

Introduce an isEndpointFinal(tags) heuristic and only write the endpoint
when the tag bag looks stable — either 'resource.name' is set, or both
'http.method' and 'http.route' are. Otherwise mark the context as
needsEndpoint and re-check on every 'dd-trace:span:tags:update' fire
(switched from webTagsCache.resolvedCh, which only fires on presence
transitions and would miss content-only updates).

Addresses Codex review point #2 on #9210: HTTP plugins routinely set
'http.method' up front and add 'http.route' (plus 'resource.name')
later once routing has resolved. The writer previously committed the
endpoint on first activation, so an out-of-process reader sampling
mid-request saw a bare 'GET' as the endpoint for a call to
'/users/:id'.

OTEP-4947 duplicates are last-wins, so a later appendAttributes would
overwrite the interim value for readers that decode the record in
full — but a sampling reader can still observe the incomplete value.
Introduce an isEndpointFinal(tags) heuristic and only write the
endpoint when the tag bag looks stable — either 'resource.name' is
set, or both 'http.method' and 'http.route' are. Otherwise mark the
context as needsEndpoint and re-check on every
'dd-trace:span:tags:update' fire (switched from
webTagsCache.resolvedCh, which only fires on presence transitions and
would miss content-only updates).

Detaching the finished span's ThreadContext from the current async-context
frame only covers that one frame. Sibling frames, and continuations the span
scheduled before finishing, inherit the same ThreadContext reference; in ACF
mode no `before` hook exists and no storage:enter fires in those frames to
overwrite the record, so an out-of-process reader kept seeing the finished
span as the active thread context there.

Use the new ThreadContext.invalidate() from @datadog/pprof 5.18.0, which
marks the record's `valid` byte 0 in place and so drops it out of scope for
every frame holding the reference at once. It runs unconditionally: the
frame calling span.finish() is not necessarily the frame holding that span's
context (a client span finished from a callback where the parent server span
is active, or any manual finish() from an unrelated context), and the record
dies with the span regardless of who holds it. clearContext() stays gated on
the current frame actually being the holder — that call is only about making
the record collectable rather than leaving an invalid one attached.

Reported by codex on #9210.

The endpoint name a web-server span's tag bag yields changes as the request
progresses, and the two consumers of that bag disagreed about what to do
about it.

datadog-plugin-next starts its request span with `resource.name: req.method`
and only replaces it with `${req.method} ${page}` once the page is known. The
OTEP-4947 writer treated any `resource.name` as a settled value, so a Next
request's record committed a bare `GET` on first activation and ignored the
resolved route forever. The same hole existed for `http.route` arriving on a
span whose `resource.name` was still the bare method, because
endpointNameFromTags prefers `resource.name`: what got written was the
placeholder even though the route was known. Finality is now decided on the
computed value rather than on which tags are present, which covers both.

That predicate moves to profiling/webspan-utils.js next to
endpointNameFromTags, since the wall profiler needs it too: it resolves
endpoint labels lazily at serialization time and so never saw the problem,
but the fallback endpoint it snapshots mid-request for when the tag bag is
unreadable later is never refreshed once set, and could be pinned to a bare
`GET`.

Records built before the endpoint settles also have to be filled in
afterwards, and only the request span's own record was. A descendant resolves
to its nearest web-server ancestor's tag bag and gets its own record with its
own endpoint copy, but the tags update carrying the route is published for the
ancestor, which cannot enumerate its descendants — so a span entered during
the deferral window never got an endpoint at all. web-tags-cache now announces
the moment a request's endpoint settles on endpointResolvedCh, and the writer
keeps the records waiting on that announcement grouped by the tag bag they are
waiting on, filling in every one of them at once. Records whose span finished
in the meantime are skipped: onSpanFinished already invalidated them.

Driving that off the cache's transition channels rather than off
`dd-trace:span:tags:update` directly leaves one subscriber on that hot channel
instead of two, and removes the writer's ordering dependency on the cache
having processed an update before it reads the cache.

web-tags-cache had no spec of its own despite now having two consumers; this
adds one pinning both transitions and the activation refcount.

Reported by codex on #9210.

…prof

Both failures this prevents would have surfaced from inside a diagnostic-channel
subscriber, which runs inline with the tracer's hot path, so the exception would
have landed in application code.

The compatibility check gated the otelThreadCtx namespace but not the
ThreadContext methods the writer calls on it. An older or overridden
@datadog/pprof exposing the namespace without invalidate() would pass the gate
and then throw out of the span-finish path and up through DatadogSpan#finish()
the first time an activated span finished. The check now covers appendAttributes,
enter and invalidate as well, and names the missing member in the warning.

@datadog/pprof also decides whether AsyncContextFrame is available by inspecting
process.execArgv, and throws from enter() when it concludes it is not. That
disagrees with the feature detection behind isACFActive whenever the flag reached
Node by another route, which is reachable today:

  $ NODE_OPTIONS=--experimental-async-context-frame node -e '...'   # Node 22.23.2
  {"isACFActive":true,"execArgv":[],"pprofWouldThrow":true}

Node 22 and 23 accept the flag in NODE_OPTIONS (Node 24 rejects it, and does not
need it), and a worker thread created with an explicit execArgv loses it too. In
those processes the first span activation would have thrown from enter() into
whatever code triggered it. start() now installs and detaches one throwaway
context up front and declines to start if that fails, so an unusable pprof costs
a warning instead of an application-visible exception.

The execArgv inference is worth replacing with feature detection upstream in
pprof-nodejs; this check is what keeps a dd-trace release safe against any
version that still has it.

Reported by codex on #9210.

The shared web-tags cache records "no web-server ancestor" for a span and
never revisits it, but that answer expires: plugins set `span.type` after
creating the span — TracingPlugin.startSpan activates it before addRequestTags
runs — so a child created in that window walks past an ancestor that is about
to become a web-server span, and caches a miss for a chain that is about to
have one.

Promotion can't find those descendants, since the walk only goes upwards. So a
promotion now bumps a generation counter, and an empty answer older than the
counter is walked again on the next lookup. Resolved answers are untouched (the
cached bag is the ancestor's live tag object), and a span with no parent is
stamped as permanently empty, since only its own promotion could change it and
onTagsUpdate already handles that. When a re-walk turns an empty answer into a
real one, the cache publishes resolvedCh for that span, the same announcement a
promoted span gets, so a consumer doesn't have to care which way the ancestry
appeared.

The counter lives on the trace, not in the module. A promotion can only
invalidate empty answers within its own trace, because the walk follows
`_parentId` through `_trace.started` and never leaves it — while a
process-global counter would have every HTTP request's promotion invalidate
empty answers in unrelated traces, making a long-lived non-web span re-walk its
chain once per request served elsewhere, from the storage-enter path.

Invalidation alone fixes nothing, because both consumers only ask the cache
while building their per-span state, and the spans this affects already have
theirs built. So each now asks again for state built from an empty answer:

- the OTEP-4947 writer re-checks on re-entry when a record was built with no
  web-server ancestor, and attaches the endpoint or enlists the record for the
  request's endpoint announcement. Guarded so a re-entrant announcement from
  inside the lookup can't append the endpoint twice.
- the wall profiler re-checks in #getProfilingContext when the snapshot it
  holds has no webTags, since #spanTagsUpdated only fires for a span promoted
  itself, never for descendants that walked past it beforehand.

Both re-checks cost two property reads plus, at most, the cache's own
generation compare — a walk only happens when a promotion in that trace has
actually invalidated something.

Two test-harness inaccuracies are fixed along the way, both of which had been
hiding behaviour rather than testing it: web-tags-cache.spec.js's makeSpan
returned a fresh object from context() per call, so spying on it counted calls
on a throwaway and the "walks the parent chain once" assertion held vacuously;
and wall.spec.js's makeChildSpan gave the child its own _trace object, so
parent and child were in different traces, which no real trace chunk is.

Reported by codex on #9210 and #9805.

Mirrors the active trace ID, span ID, local root span ID and current endpoint
into a thread-local OTEP-4947 record, so an out-of-process eBPF reader can
attribute samples without going through the tracer. The record is discovered via
the otel_thread_ctx_nodejs_v1 TLS symbol exported by the @datadog/pprof addon,
and decoded using an OTEP-4719 process context published through libdatadog's
process discovery (threadlocal.* attribute key map, schema version, and the V8
layout constants a reader needs to walk into the record).

Off by default, behind DD_TRACE_OTEL_CTX_ENABLED. Requires Linux and an active
AsyncContextFrame (default from Node 24, opt-in on 22/23), and refuses to start
unless the installed @datadog/pprof exposes every API member the writer calls
and a context can actually be installed in this process — an unusable pprof
costs a log line rather than an exception thrown from a hot-path diagnostic
channel subscriber.

One ThreadContext is built per span on first activation and cached on the span,
so re-entry in another async-context frame re-installs the same reference rather
than allocating. On span finish the record is invalidated in place, which drops
it out of scope for every frame that inherited it — sibling frames and
continuations the span scheduled before finishing — since no later storage event
reaches those.

The endpoint is held back until its value settles: plugins publish interim
routing tags, and datadog-plugin-next seeds resource.name with the bare request
method, so publishing early would leave a reader attributing samples to "GET".
Once a request's endpoint resolves it is appended to every record built under
that request, the request span's own and each descendant's.

Mirrors the active trace ID, span ID, local root span ID and current endpoint
into a thread-local OTEP-4947 record, so an out-of-process eBPF reader can
attribute samples without going through the tracer. The record is discovered via
the otel_thread_ctx_nodejs_v1 TLS symbol exported by the @datadog/pprof addon,
and decoded using an OTEP-4719 process context published through libdatadog's
process discovery (threadlocal.* attribute key map, schema version, and the V8
layout constants a reader needs to walk into the record).

Off by default, behind DD_TRACE_OTEL_CTX_ENABLED. Requires Linux and an active
AsyncContextFrame (default from Node 24, opt-in on 22/23), and refuses to start
unless the installed @datadog/pprof exposes every API member the writer calls
and a context can actually be installed in this process — an unusable pprof
costs a log line rather than an exception thrown from a hot-path diagnostic
channel subscriber.

One ThreadContext is built per span on first activation and cached on the span,
so re-entry in another async-context frame re-installs the same reference rather
than allocating. On span finish the record is invalidated in place, which drops
it out of scope for every frame that inherited it — sibling frames and
continuations the span scheduled before finishing — since no later storage event
reaches those.

The endpoint is held back until its value settles: plugins publish interim
routing tags, and datadog-plugin-next seeds resource.name with the bare request
method, so publishing early would leave a reader attributing samples to "GET".
Once a request's endpoint resolves it is appended to every record built under
that request, the request span's own and each descendant's.

Mirrors the active trace ID, span ID, local root span ID and current endpoint
into a thread-local OTEP-4947 record, so an out-of-process eBPF reader can
attribute samples without going through the tracer. The record is discovered via
the otel_thread_ctx_nodejs_v1 TLS symbol exported by the @datadog/pprof addon,
and decoded using an OTEP-4719 process context published through libdatadog's
process discovery (threadlocal.* attribute key map, schema version, and the V8
layout constants a reader needs to walk into the record).

Off by default, behind DD_TRACE_OTEL_CTX_ENABLED. Requires Linux and an active
AsyncContextFrame (default from Node 24, opt-in on 22/23), and refuses to start
unless the installed @datadog/pprof exposes every API member the writer calls
and a context can actually be installed in this process — an unusable pprof
costs a log line rather than an exception thrown from a hot-path diagnostic
channel subscriber.

One ThreadContext is built per span on first activation and cached on the span,
so re-entry in another async-context frame re-installs the same reference rather
than allocating. On span finish the record is invalidated in place, which drops
it out of scope for every frame that inherited it — sibling frames and
continuations the span scheduled before finishing — since no later storage event
reaches those.

The endpoint is held back until its value settles: plugins publish interim
routing tags, and datadog-plugin-next seeds resource.name with the bare request
method, so publishing early would leave a reader attributing samples to "GET".
Once a request's endpoint resolves it is appended to every record built under
that request, the request span's own and each descendant's.

Mirrors the active trace ID, span ID, local root span ID and current endpoint
into a thread-local OTEP-4947 record, so an out-of-process eBPF reader can
attribute samples without going through the tracer. The record is discovered via
the otel_thread_ctx_nodejs_v1 TLS symbol exported by the @datadog/pprof addon,
and decoded using an OTEP-4719 process context published through libdatadog's
process discovery (threadlocal.* attribute key map, schema version, and the V8
layout constants a reader needs to walk into the record).

Off by default, behind DD_TRACE_OTEL_CTX_ENABLED. Requires Linux and an active
AsyncContextFrame (default from Node 24, opt-in on 22/23), and refuses to start
unless the installed @datadog/pprof exposes every API member the writer calls
and a context can actually be installed in this process — an unusable pprof
costs a log line rather than an exception thrown from a hot-path diagnostic
channel subscriber.

One ThreadContext is built per span on first activation and cached on the span,
so re-entry in another async-context frame re-installs the same reference rather
than allocating. On span finish the record is invalidated in place, which drops
it out of scope for every frame that inherited it — sibling frames and
continuations the span scheduled before finishing — since no later storage event
reaches those.

The endpoint is held back until its value settles: plugins publish interim
routing tags, and datadog-plugin-next seeds resource.name with the bare request
method, so publishing early would leave a reader attributing samples to "GET".
Once a request's endpoint resolves it is appended to every record built under
that request, the request span's own and each descendant's.